home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / lisp / kcl / kcl.lha / doc / porting < prev    next >
Lisp/Scheme  |  1987-06-04  |  30KB  |  883 lines
  1.  
  2. \(progn
  3.  
  4.   (defmacro set-page (name) `(setq ,name *page-number*))
  5.   (defun date ()
  6.     (multiple-value-bind (sec min hour date month year) (get-decoded-time)
  7.       (do-string
  8.     (format nil
  9.                 "~[January~;February~;March~;April~;May~;June~;July~;~
  10.            August~;September~;October~;November~;December~] ~
  11.                  ~d, ~d"
  12.         (1- month)
  13.                 date
  14.                 year))))
  15.   (defun fr () (setq *current-font* *font-roman*))
  16.   (defun fi () (setq *current-font* *font-italic*))
  17.   (defun fb () (setq *current-font* *font-bold*))
  18.   (defun fp () (setq *current-font* *font-prop*))
  19.   (defun fg () (setq *current-font* *font-big*))
  20.   (defun sm () (setq *old-left-margin* *left-margin*)
  21.            (setq *left-margin* (+ (mark-column) *left-margin*)))
  22.   (defun rm () (do-line-so-far) (setq *left-margin* *old-left-margin*))
  23.   (defun ra () (right-adjust))
  24.   (defun ce () (centering))
  25.   (defun br () (break-line))
  26.   (defun lm (n) (setq *left-margin* n))
  27.   (defun bd () (setq *left-margin* 100))
  28.   (defun endd () (do-line-so-far) (setq *left-margin* 0))
  29. )
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36. \(ra)Revised \(date)
  37.  
  38.  
  39.  
  40.  
  41.  
  42. \(fg) 
  43. \(ce)A Guide to Porting Kyoto Common Lisp
  44.  
  45. \(fr)
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52. \(fi)
  53. \(ce)by
  54. \(fr)
  55.  
  56. \(ce)Masami Hagiya
  57. \(ce)Taiichi Yuasa
  58.  
  59.  
  60. \(ce)Research Institute for Mathematical Sciences
  61. \(ce)Kyoto University
  62. \(ce)Kyoto, 606, Japan
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77. \(ce)Copyright (C) 1984 Taiichi Yuasa and Masami Hagiya
  78.  
  79. \(fg) 
  80.  
  81. Introduction
  82. \(fr)
  83.      This document explains how to construct the KCL system
  84. and how to port KCL.  It will also be useful for customizing the existing
  85. versions of KCL.
  86.  
  87.     1. KCL/AOS
  88.        Machine: \(sm)Data General's Eclipse MV series super-minicomputers (MV10000, MV8000, MV6000, and MV4000)\(rm)
  89.        Operating System: \(sm)Data General's original AOS/VS (Advanced Operating System / Virtual Storage)\(rm)
  90.  
  91.     2. KCL/VAX
  92.        Machine: \(sm)Digital Equipment Corporation's VAX 11 series machines (VAX 11/780 and VAX 11/750)\(rm)
  93.        Operating System: UNIX 4.2 bsd
  94.  
  95.     3. KCL/SUN
  96.        Machine: \(sm)Sun Microsystems' Sun Workstation (MC68000/MC68020 base)\(rm)
  97.        Operating System: UNIX 4.2 bsd
  98.  
  99.     4. KCL/UST
  100.        Machine: \(sm)Sumitomo Electric Industries and Digital Computer Laboratory's personal workstation Ustation E15 (MC68000 base)\(rm)
  101.        Operating System: UNIX System V (Uniplus' version)
  102.  
  103.     5. KCL/DGX
  104.        Machine: \(sm)Data General's Eclipse MV series super-minicomputers (MV10000, MV8000, MV6000, and MV4000)\(rm)
  105.        Operating System: DGUX, Data General's native UNIX
  106.  
  107.     6. KCL/3B2
  108.        Machine: \(sm)AT&T's 3B2 series workstations\(rm)
  109.        Operating System: UNIX System V
  110.  
  111.     7. KCL/SEQ
  112.        Machine: \(sm)Sequent Balance 8000 (NS32032 base)\(rm)
  113.        Operating System: UNIX 4.2 bsd
  114.  
  115.     8. KCL/UTS
  116.        Machine: \(sm)M Series\(rm)
  117.        Operating System: UNIX System V
  118.  
  119.     9. KCL/NWS
  120.        Machine: \(sm)Sony NEWS (MC68020 base)\(rm)
  121.        Operating System: UNIX 4.2 bsd
  122.  
  123. Most of the source files of KCL are shared by these versions, but
  124. some source files are specific to some versions of KCL.
  125. In this document, we are mainly concerned with the UNIX BSD
  126. versions, and
  127. we explain how to port KCL to UNIX machines.  However,
  128. this document is also helpful for those people
  129. who want to port KCL to non-UNIX machines,
  130. since it explains how to construct the KCL system in general.
  131.  
  132.      To port KCL to UNIX machines running under UNIX System V
  133. (or System III, XENIX, VENIX, etc.) is much more difficult
  134. than to port KCL to UNIX machines running under UNIX BSD.  Particularly,
  135. the loader (fasloader)
  136. and the memory dump routine should be rewritten.  Some of the standard
  137. library functions of C used in KCL
  138. may not be provided in UNIX System V.  Refer to Section 11 of
  139. this document for the details.
  140.  
  141.      Some of the C source files of KCL contain the \(fp)#ifdef\(fr)
  142. preprocessor command
  143. followed by either of the following identifiers:
  144.  
  145.     \(fi)Identifier        Use\(fp)
  146.     -----------------------------------------
  147.     VAX        \(fr)VAX/UNIX 4.2BSD\(fp)
  148.     SUN        \(fr)SUN-2 Releases 1.2 and 2\(fp)
  149.     SUN2R3        \(fr)SUN-2 Release 3\(fp)
  150.     SUN3        \(fr)SUN-3\(fp)
  151.     ATT3B2        \(fr)3B2\(fp)
  152.     E15        \(fr)Ustation E15 (System V)\(fp)
  153.     NEWS        \(fr)Sony NeWS\(fp)
  154.     MC68K        \(fr)MC68000\(fp)
  155.     MC68020        \(fr)MC68020\(fp)
  156.     NS32K        \(fr)NS32032\(fp)
  157.     IEEEFLOAT    \(fr)IEEE floating format\(fp)
  158.     UNIX        \(fr)UNIX\(fp)
  159.     BSD        \(fr)UNIX 4.2BSD\(fp)
  160.     ATT        \(fr)UNIX System V\(fp)
  161.     DGUX        \(fr)DG/UX\(fp)
  162.     AOSVS        \(fr)AOS/VS\(fp)
  163.     AV        \(fr)Average (i.e., Non-MV) architecture\(fp)
  164.     MV        \(fr)ECLIPSE/MV\(fp)
  165. \(fr)
  166.  
  167. Each version of KCL has a key switch by which other switches for the
  168. version are automatically defined.
  169.  
  170.     \(fi)Version        Key Switch    Other Switches\(fp)
  171.     ----------------------------------------------
  172.     KCL/VAX        VAX        UNIX BSD AV
  173.     KCL/SUN        SUN        UNIX BSD MC68K IEEEFLOAT AV
  174.             SUN2R3        UNIX BSD MC68K IEEEFLOAT AV
  175.             SUN3        UNIX BSD MC68020 IEEEFLOAT AV
  176.     KCL/3B2        ATT3B2        UNIX ATT IEEEFLOAT AV
  177.     KCL/UST        E15        UNIX MC68K IEEEFLOAT AV
  178.     KCL/DGX        DGUX        UNIX MV
  179.     KCL/AOS        AOSVS        MV
  180.     KCL/SEQ        SEQ        UNIX BSD NS32K IEEEFLOAT AV
  181.     KCL/UTS        S3000        UNIX ATT AV
  182.     KCL/NWS        NEWS        UNIX BSD MC68020 IEEEFLOAT AV
  183. \(fr)
  184.  
  185.      Some of the Lisp source files of KCL contain the \(fp)#+\(fr)
  186. and \(fp)#-\(fr)
  187. read-macros with the feature \(fp)AOS\(fr) or \(fp)UNIX\(fr).  The Common
  188. Lisp variable \(fp)*features*\(fr) is created and initialized
  189. in \(fp)c/main.c\(fr) (see below).  The initial value is set
  190. according to which of the above identifiers is defined.  For the UNIX
  191. versions, the symbol \(fp)UNIX\(fr) is in the features.
  192.  
  193.      It is desirable to make a user whose name is \(fp)kcl\(fr)
  194. and load the distribution tape directly under his home directory,
  195. and put the directory \(fp)bin\(fr) (see below) at the end of the search path,
  196. since it contains the commands for system generation.  (Some of the commands
  197. assume the C shell \(fp)csh\(fr) rather than the Bourne shell \(fp)sh\(fr).)
  198.  
  199.      Unfortunately, the C source files of KCL use identifiers much longer
  200. than seven characters.  It will take much effort to port KCL to a poor
  201. operating system
  202. in which identifiers are recognized by the first seven characters,
  203. such as the old versions of UNIX System V and System III.
  204.  
  205.      In this document,
  206. we first discuss how to generate the KCL system,
  207. explaining the components of KCL and how they are combined.  Then,
  208. we give some hints for porting KCL to UNIX machines
  209. by discussing the hardware-dependent parts
  210. and the operating-system-dependent parts in detail.
  211.  
  212.      Although most of the KCL code was written by us, the authors of this
  213. \(fi)Guide\(fr), several people have contributed to the development of
  214. the current KCL.  We wish to express our thanks especially to the following
  215. people.  Mr. Teruo Yabe and Mr. Toshiyasu Harada of Nippon Data General
  216. helped us coding during the development of the first version of KCL.  
  217. Dr. Skef Wholey at CMU allowed us to use their code for the function
  218. \(fp)rationalize\(fr).  Dr. Yuuichi Ohta at the University of Tsukuba
  219. ported KCL onto Sequent Balance 8000, writing the KCL/SEQ specific code.
  220.  
  221.  
  222. \(fg)
  223. 1. Directories
  224. \(fr)
  225.      The distribution tape of KCL source is formatted
  226. in the UNIX \(fp)tar\(fr) format.  The following \(fp)tar\(fr) call
  227. will load all source files in the tape.
  228. \(fp)
  229.     % tar x
  230. \(fr)
  231. The source files of KCL are stored in four directories:
  232.  
  233.     \(fp)h    \(fr)header files
  234.     \(fp)c    \(fr)source files in C
  235.     \(fp)lsp    \(fr)source files in Lisp
  236.     \(fp)cmpnew    \(fr)source files of compiler in Lisp
  237.  
  238.      The object files of C source files are placed
  239. in the directory \(fp)o\(fr).
  240.  
  241.      The KCL itself is placed in the directory \(fp)unixport\(fr).  This
  242. directory contains
  243. other files needed for the system generation.
  244.  
  245.      The directory \(fp)bin\(fr) contains the commands used
  246. in the system generation.
  247.  
  248. \(fg)
  249. 2. Makefiles
  250. \(fr)
  251.      Each of the directories \(fp)bin\(fr), \(fp)o\(fr), \(fp)lsp\(fr),
  252. \(fp)cmpnew\(fr), and \(fp)unixport\(fr) has a makefile in it.
  253.  
  254.     \(fp)bin/makefile\(fr)
  255.         to prepare the commands defined in the \(fp)bin\(fr) directory
  256.     \(fp)o/makefile\(fr)
  257.         to compile the source files in the \(fp)c\(fr) directory
  258.     \(fp)lsp/makefile\(fr)
  259.         to compile the source files in the \(fp)lsp\(fr) directory
  260.     \(fp)cmpnew/makefile\(fr)
  261.         to compile the source files in the \(fp)cmpnew\(fr) directory
  262.     \(fp)unixport/makefile\(fr)
  263.         to link and initialize KCL
  264.  
  265. There is another \(fp)makefile\(fr) in the KCL directory (i.e. the
  266. current working directory when you read in the source tape).
  267. This makefile does all the jobs of the above makefiles.
  268.  
  269.      These makefiles are intended for those users who are responsible
  270. for the maintenance of KCL/VAX or KCL/SUN at their sites.  (We do not
  271. know whether these makefiles are useful when KCL is ported to yet
  272. another machine/os.)  The makefiles \(fp)o/makefile\(fr) and
  273. \(fp)unixport/makefile\(fr) contain version-dependent parts, as indicated
  274. \(fp)
  275.   MACHINE = SUN3
  276.   #    Select 'VAX', 'SUN', 'SUN2R3', 'SUN3', 'ISI', 'SEQ', 'IBMRT',
  277.   #    or 'NEWS'.
  278.  
  279.   CHTAB    = sun_chtab.s
  280.   #    Select 'char_table.s' or 'sun_chtab.s'.
  281.   #    1) char_table.s : for VAX, SEQ and NEWS
  282.   #    2) sun_chtab.s  : for SUN, SUN2R3 and SUN3
  283.   #    3) isi_chtab.s  : for ISI
  284.   #    4) ibmrt_chtab.s: for IBMRT
  285. \(fr)
  286. in \(fp)o/makefile\(fr) and
  287. \(fp)
  288.   MACHINE = SUN3
  289.   #    Select 'VAX', 'SUN', 'SUN2R3', 'SUN3', 'ISI', 'SEQ', 'IBMRT',
  290.   #    or 'NEWS'.
  291. \(fr)
  292. in \(fp)unixport/makefile\(fr).
  293. Check these parts before using these files and, if necessary, modify them.
  294.  
  295.      To install KCL/VAX or KCL/SUN from the source for the first time,
  296. do the following at the KCL directory.
  297. \(fp)
  298.     % su
  299.     # cp h/cmpinclude.h /usr/include
  300.     # exit
  301.     % make
  302.     % su
  303.     # make install
  304.     # exit
  305.     %
  306. \(fr)
  307. To revise KCL, do the following at the KCL directory.
  308. \(fp)
  309.     % make
  310. \(fr)
  311.  
  312. \(fg)
  313. 3. Header Files
  314. \(fr)
  315.      All the header files for C source files are stored
  316. in the \(fp)h\(fr) directory.  The header file \(fp)include.h\(fr)
  317. is the toplevel header file;
  318. it includes other header files needed for compiling C source files.  It
  319. also defines the appropriate switches
  320. from the key switch of the version.  Since
  321. each C source file includes \(fp)include.h\(fr)
  322. by the preprocessor statement
  323. \(fp)
  324.     #include "include.h",
  325. \(fr)
  326. there is a copy of \(fp)include.h\(fr) in the \(fp)c\(fr) directory.
  327.  
  328.      Including \(fp)include.h\(fr) will include \(fp)stdio.h\(fr)
  329. and \(fp)ctype.h\(fr),
  330. which are the standard include files of C.
  331.  
  332.      The C source files that define number functions
  333. also include \(fp)h/num_include.h\(fr) by another preprocessor statement
  334. \(fp)
  335.     #include "num_include.h".
  336. \(fr)
  337. \(fp)num_include.h\(fr) is linked to the \(fp)c\(fr) directory.
  338.  
  339. \(fg)
  340. 4. C Source Files
  341. \(fr)
  342.      Some of the source files in the \(fp)c\(fr) directory have
  343. the suffix "\(fp).d\(fr)".  These files should be preprocessed
  344. by the preprocessor called \(fp)dpp\(fr) (\(fi)D\(fr)efun \(fi)P\(fr)re\(fi)P\(fr)rocessor) before compiled by the C compiler.
  345. The source file of \(fp)dpp\(fr) (i.e., \(fp)dpp.c\(fr)) is in
  346. the \(fp)bin\(fr) directory.
  347. It should be compiled (in the \(fp)bin\(fr) directory) by
  348. \(fp)
  349.     % cc -O -o dpp -DUNIX dpp.c
  350. \(fr)
  351. Or, you can use the makefile in the \(fp)bin\(fr) directory.
  352. \(fp)
  353.     % cd bin
  354.     % make
  355. \(fr)
  356. \(fp)dpp\(fr) is called by
  357. \(fp)
  358.     % dpp \(fi)filename\(fr)
  359.  
  360. This will preprocess \(fi)filename\(fp).d\(fr) and
  361. produce \(fi)filename\(fp).c\(fr).
  362.  
  363.      Each C source file (after preprocessed by \(fp)dpp\(fr)) is compiled
  364. by the following command.
  365. \(fp)
  366.     % cc -D\(fi)name\(fp) -DMAXPAGE=\(fi)mp\(fp) -DVSSIZE=\(fi)vs\(fp) -O -c \(fi)filename\(fp).c
  367. \(fr)
  368. \(fi)name\(fr) is the key switch of the KCL version.
  369. You are recommended to invent another name for your
  370. machine.  \(fi)mp\(fr) is the maximum number of pages
  371. (1 page = 2048 bytes) the KCL process will use.  It does not contain the
  372. space for the stack segment,
  373. but does contain the space for the text, data, and bss.  \(fi)vs\(fr) is
  374. the size of the value stack of KCL in words.
  375.  
  376.      The object files of the C source files
  377. should be placed in the \(fp)o\(fr) directory;
  378. move the output of the C compiler to the \(fp)o\(fr) directory.
  379. \(fp)
  380.     % mv \(fi)filename\(fp).o ../o
  381. \(fr)
  382.      The command \(fp)bin/ccc\(fr) does all the task;
  383. \(fp)
  384.     % ccc \(fi)filename\(fr)
  385.  
  386. will preprocess the source file, compile the source file and move the
  387. object file to the \(fp)o\(fr) directory.  \(fi)filename\(fr) is the file
  388. name of the
  389. source file without the suffix (\(fp).c\(fr) or \(fp).d\(fr)).  The values
  390. of \(fi)mp\(fr) and \(fi)vs\(fr) used in \(fp)ccc\(fr) are
  391. \(fp)16384\(fr) (32 Mbytes) and \(fp)2048\(fr) (words).  The command
  392. \(fp)bin/cccall\(fr) compiles all the C source files,
  393. assembles an assembler file (see below),
  394. and places the output in the \(fp)o\(fr) directory.
  395. Or, you can use the makefile in the \(fp)o\(fr) directory.
  396. \(fp)
  397.     % cd o
  398.     % make
  399. \(fr)
  400.      Two C source files contain \(fp)asm\(fr) statements.
  401. One is for double-word
  402. multiplication and division (\(fp)earith.c\(fr))
  403. and another is for bit-table operation (\(fp)bitop.c\(fr)).  Refer to
  404. Section 10.1.
  405.  
  406. \(fg)
  407. 5. The Assembler File
  408. \(fr)
  409.      There is one assembler file that should be assembled
  410. by \(fp)as\(fr).  This file allocates the table
  411. of character objects (\(fp)character_table\(fr)).
  412. For the VAX and SEQ versions,
  413. it has the name \(fp)char_table.s\(fr),
  414. for the SUN, SUN2R3 and SUN3 versions \(fp)sun_chtab.s\(fr).
  415. The output should be placed
  416. in \(fp)o/char_table.o\(fr) even for \(fp)sun_chtab.s\(fr).
  417.  
  418.      This file only defines the symbol \(fp)_character_table\(fr)
  419. (in the data or bss segment)
  420. and allocates a space of 1024 bytes and a space of 2048 bytes
  421. before and after the symbol, respectively.  This file is needed because
  422. of the pathological phenomenon
  423. that C \(fp)char\(fr)'s may sometimes be signed.
  424.  
  425. \(fg)
  426. 6. Libraries
  427. \(fr)
  428.      Some of the Common Lisp functions are written
  429. in Lisp (Common Lisp).  They are divided into several library files
  430. in the \(fp)lsp\(fr) directory.
  431. These files have been compiled by the KCL compiler,
  432. and for each library file, the following files are prepared:
  433.  
  434.     \(fi)filename\(fp).lsp\(fr)    Lisp source file
  435.     \(fi)filename\(fp).c\(fr)    translated C source file
  436.     \(fi)filename\(fp).h\(fr)    header file for \(fi)filename\(fp).c\(fr)
  437.     \(fi)filename\(fp).data\(fr)    data file in the form of text
  438.  
  439. The translated C source file \(fi)filename\(fp).c\(fr) includes
  440. the header files \(fp)h/cmpinclude.h\(fr) and \(fi)filename\(fp).h\(fr).
  441. Since the header file \(fp)cmpinclude.h\(fr) is included by the preprocessor
  442. statement
  443. \(fp)
  444.     #include <cmpinclude.h>
  445. \(fr)
  446. it should be moved (or linked) to the directory that stores
  447. standard include files of C (say, \(fp)/usr/include\(fr)).  Each
  448. translated C source file is compiled
  449. by the following command.
  450. \(fp)
  451.     % cc -O -c \(fi)filename\(fp).c
  452. \(fr)
  453. Note that the translated C source files
  454. are completely independent of the version of KCL.  The data file
  455. should be attached at the end of the object file,
  456. using, say, the \(fp)cat\(fr) command.
  457. \(fp)
  458.     % cat \(fi)filename\(fp).data >> \(fi)filename\(fp).o
  459. \(fr)
  460. The result should \(fi)not\(fr) be moved to the \(fp)o\(fr) directory.
  461.  
  462.      These object files can be loaded by the fasloader of KCL.  But
  463. in this case,
  464. the text of the object will be placed in the bss segment of the KCL process
  465. and the garbage collector of KCL should take care of it.  So, it is desirable
  466. to link the object with the kernel of KCL;
  467. then the text will be in the text segment and become sharable
  468. among the users.  By default, all the library files of KCL are included
  469. in the KCL system (refer to Section 8).
  470.  
  471.      The command \(fp)bin/libccall\(fr)
  472. compiles all the translated C source files in the \(fp)lsp\(fr) directory
  473. and attaches the corresponding data files to them.
  474. Or, you can use the makefile in the \(fp)lsp\(fr) directory.
  475. \(fp)
  476.     % cd lsp
  477.     % make
  478. \(fr)
  479.  
  480.      The files \(fp)export.lsp\(fr), \(fp)autoload.lsp\(fr), and
  481. \(fp)setdoc.lsp\(fr) in the \(fp)lsp\(fr) directory
  482. should not be compiled; their Lisp sources are loaded at the system
  483. initialization.  \(fp)export.lsp\(fr) exports the external symbols
  484. in the \(fp)lisp\(fr) package.  Not all the external symbols
  485. in the \(fp)lisp\(fr) package
  486. are exported by \(fp)export.lsp\(fr);
  487. some are created in the initialization routines written in C
  488. and do not appear in \(fp)export.lsp\(fr).  \(fp)autoload.lsp\(fr) was
  489. once used to define the autoloaded functions.  Since all the library files
  490. are included in the system now,
  491. it is used to define some of the non-compiled functions,
  492. such as environment queries and editor interfaces,
  493. which do not require efficiency, but are expected
  494. to be customized.  Since they are not compiled,
  495. you have only to rewrite \(fp)autoload.lsp\(fr) to modify
  496. these functions.  (Refer to Section 12.)  \(fp)setdoc.lsp\(fr) sets the
  497. online documentations of built-in symbols.
  498.  
  499. \(fg)
  500. 7. The Compiler
  501. \(fr)
  502.      The compiler source files (in the \(fp)cmpnew\(fr) directory)
  503. should be processed in the same manner as library files
  504. in the \(fp)lsp\(fr) directory.  The files
  505. \(fp)cmpmain.lsp\(fr), \(fp)cmpopt.lsp\(fr), and \(fp)lfun_list.lsp\(fr)
  506. should not be compiled.  These three files are loaded
  507. by \(fp)init_kcl.lsp\(fr) (see below).
  508.  
  509.      The command \(fp)bin/cmpccall\(fr)
  510. compiles all the translated C source files in the \(fp)cmpnew\(fr) directory
  511. and attaches the corresponding data files.
  512. Or, you can use the makefile in the \(fp)cmpnew\(fr) directory.
  513. \(fp)
  514.     % cd cmpnew
  515.     % make
  516. \(fr)
  517.  
  518.      \(fp)cmpnew/cmpmain.lsp\(fr) defines the top-level
  519. of the compiler.  Since this file contains the code to call the C compiler,
  520. it depends on the operating system.
  521.  
  522. \(fg)
  523. 8. Raw System
  524. \(fr)
  525.      The raw system (the KCL system without system initialization)
  526. is made by linking
  527.  
  528.     object files in the \(fp)o\(fr) directory
  529.     object files in the \(fp)lsp\(fr) directory
  530.     object files in the \(fp)cmpnew\(fr) directory
  531.     \(fp)sys_kcl.o\(fr) in the \(fp)unixport\(fr) directory
  532.  
  533. Not all the object files in the \(fp)lsp\(fr) directory have to be linked
  534. in the raw
  535. system.  Only the following four files are necessary:
  536. \(fp)
  537.     defmacro.o
  538.     evalmacros.o
  539.     module.o
  540.     toplevel.o
  541. \(fr)
  542. Other library files are optional;
  543. they may be included in the system
  544. or loaded explicitly by the user,
  545. or made autoloaded.  The compiler is also optional;
  546. you can make a system that does not include the KCL compiler.
  547. By default, all the library files and the compiler
  548. are included in the system.
  549.  
  550.      \(fp)sys_kcl.o\(fr) contains the initialization routine written in C.
  551. It is made by compiling \(fp)unixport/sys_kcl.c\(fr).
  552.  
  553.      Since the KCL system uses the "mathematical library" of C,
  554. the linkage editor should be invoked with the \(fp)-lm\(fr) option.
  555.  
  556.      The command \(fp)make_kcl\(fr) in the \(fp)unixport\(fr) directory
  557. compiles \(fp)sys_kcl.c\(fr)
  558. and links all the above object files with the C library,
  559. makes the raw system, initializes it,
  560. and saves the initialized system (see below).
  561. Or, you can use the makefile in the \(fp)unixport\(fr) directory.
  562. \(fp)
  563.     % cd unixport
  564.     % make
  565. \(fr)
  566. The raw system is
  567. named \(fp)raw_kcl\(fr) (in the \(fp)unixport\(fr) directory).  You should
  568. change the current directory to \(fp)unixport\(fr)
  569. before issuing \(fp)make_kcl\(fr).
  570.  
  571. \(fg)
  572. 9. Initialization
  573. \(fr)
  574.      The initialization should be done in the \(fp)unixport\(fr) directory;
  575. you should change the current directory to \(fp)unixport\(fr).
  576.  
  577.      The raw system is invoked by typing
  578. \(fp)
  579.     % raw_kcl.
  580. \(fr)
  581. After printing the banner and initializing the raw system,
  582. \(fp)raw_kcl\(fr) will output the prompt.
  583. \(fp)
  584.     >
  585. \(fr)
  586. You are now at the toplevel.
  587. But the libraries and the compiler have not been initialized yet.
  588. The initialization of the library and the compiler
  589. is done by loading the file \(fp)unixport/init_kcl.lsp\(fr).
  590. \(fp)
  591.     >(load "init_kcl")
  592. \(fr)
  593. After the initialization,
  594. the system is automatically saved
  595. in the file \(fp)saved_kcl\(fr) in the \(fp)unixport\(fr) directory,
  596. and \(fp)raw_kcl\(fr) is terminated.
  597. Here, to save the system means to dump the whole memory
  598. to an executable file (\(fp)saved_kcl\(fr) in this case).
  599.  
  600.      To change the configuration of the system,
  601. i.e., to change the set of library files to be included in the system,
  602. or to exclude the compiler,
  603. you should rewrite the following files.
  604. \(fp)
  605.     sys_kcl.c
  606.     init_kcl.lsp
  607.     make_kcl
  608. \(fr)
  609. These files are all in the \(fp)unixport\(fr) directory.
  610.  
  611.      A utility called \(fi)defsystem\(fr) is prepared
  612. for changing the configuration of the system.  It is written in KCL and
  613. is placed in the \(fp)unixport\(fr)
  614. directory (\(fp)defsystem.lsp\(fr)).  Actually, the above three files were
  615. produced by defsystem.  But you cannot use defsystem until you have installed
  616. KCL.  Refer to the separate documents of defsystem for the details.
  617.  
  618.      The saved KCL system may be invoked by a command similar to
  619. the command in the command file \(fp)unixport/kcl\(fr).  In
  620. \(fp)unixport/kcl\(fr), the full pathname of the saved system is specified
  621. to let the system know the pathname of itself;
  622. this is needed for the fasloader.  The saved system may take several
  623. arguments.  The first one is the pathname of
  624. the \(fp)unixport\(fr) directory (ending with '\(fp)/\(fr)');
  625. it can be omitted if the saved system is in the \(fp)unixport\(fr) directory,
  626. and if there are no further arguments.  Other arguments are specified
  627. when invoking
  628. the KCL compiler directly from the shell
  629. (by the command \(fp)unixport/lc\(fr) etc.).
  630.  
  631. \(fg)
  632. 10. Hardware-Dependent Parts
  633. \(fr)
  634.      In this section, we list those parts of KCL
  635. that depend on the hardware.
  636.  
  637.      Before that, we briefly point out
  638. those parts of the C source files of KCL
  639. that are influenced by the architecture of ECLIPSE/MV.
  640.  
  641.      ECLIPSE/MV is a word addressing machine;
  642. the byte pointer and the word pointer have different formats.
  643. Because of this peculiarity, the C source files contain many cast operators
  644. that may seem redundant for byte machines.  For the UNIX BSD versions,
  645. we only assume byte addressing machines.
  646.  
  647.      The user's address space on ECLIPSE/MV begins with \(fp)0x7000000\(fr)
  648. (in word address);
  649. each address in the user's space has the ring number 7.
  650. The ring number should always be cleared
  651. to get the page number of the address.
  652. For the UNIX BSD versions, we assume that the address space begins with \(fp)0\(fr).
  653.  
  654. \(fg)
  655. 10.1. Double-word Arithmetic and Bit-table Operation
  656. \(fr)
  657.      \(fp)c/earith.c\(fr) contains some \(fp)asm\(fr) statements
  658. that define the double-word multiplication routine \(fp)extended_mul\(fr)
  659. and the double-word division routine \(fp)extended_div\(fr).  Their
  660. formats are as follows.
  661. \(fp)
  662.     extended_mul(d, q, r, hp, lp)
  663.     int d, q, r;
  664.     int *hp, *lp;
  665. \(fr)
  666. \(fp)d\(fr), \(fp)q\(fr), and \(fp)r\(fr) are positive
  667. integers (31 bits long).
  668. The result of \(fp)d*q+r\(fr), which is 62 bits long,
  669. is divided into two words each containing 31 bits
  670. and the high and low words are stored into \(fp)*hp\(fr) and \(fp)*lp\(fr),
  671. respectively.
  672. \(fp)
  673.     extended_div(d, h, l, qp, rp)
  674.     int d, h, l;
  675.     int *qp, *rp;
  676. \(fr)
  677. \(fp)d\(fr), \(fp)h\(fr), and \(fp)l\(fr) are
  678. positive integers (31 bits long).  \(fp)(h<<31)+1\(fr) is divided
  679. by \(fp)d\(fr) and the quotient and the remainder are stored
  680. into \(fp)*qp\(fr) and \(fp)*rp\(fr), respectively.
  681.  
  682.      \(fp)c/bitop.c\(fr) defines the bit-table operations
  683. used in the garbage collector to get or set a mark bit
  684. in the mark table.  In the mark table, one bit is prepared
  685. for each word (1 word = 4 bytes).  The top address of the mark table
  686. is stored in the C global variable
  687. \(fp)mark_table\(fr) (a pointer to \(fp)int\(fr)).
  688. The bit for a word pointer \(fp)x\(fr) is accessed by
  689. \(fp)
  690.     (mark_table[x/4/32] >> (x/4%32)) & 1.
  691. \(fr)
  692. \(fp)c/bitop.c\(fr) defines
  693. three functions \(fp)get_mark_bit\(fr), \(fp)set_mark_bit\(fr),
  694. and \(fp)get_set_mark_bit\(fr),
  695. whose argument is a pointer to a word.
  696. \(fp)get_mark_bit\(fr) returns \(fp)0\(fr) or \(fp)1\(fr) according to
  697. whether the bit is off or on.
  698. \(fp)get_set_mark_bit\(fr) also returns \(fp)0\(fr) or \(fp)1\(fr),
  699. but sets the bit as \(fp)set_mark_bit\(fr) does.
  700.  
  701. \(fg)
  702. 10.2. Floating Point Numbers
  703. \(fr)
  704.      Some of the Common Lisp functions depend on the representation
  705. of floating point numbers;
  706. they include
  707. \(fp)
  708.     decode-float
  709.     scale-float
  710.     float-radix
  711.     float-digits
  712.     float-precision
  713.     integer-decode-float
  714. \(fr)
  715. In KCL, these functions are all defined in \(fp)c/num_co.c\(fr).
  716. Some floating point constants are also created in \(fp)c/num_co.c\(fr).
  717. You should look through the file \(fp)c/num_co.c\(fr) and change the code
  718. according to the representation of floating point numbers in your machine.
  719.  
  720.      The reader routine for floating point numbers does not depend
  721. on the hardware.
  722. As for the output, the C library function \(fp)sprintf\(fr) is used
  723. to get the mantissa and exponent of a floating point number.
  724. When the \(fp)IEEEFLOAT\(fr) switch is on,
  725. since the IEEE floating format is assumed,
  726. the exponent of a long floating point number can be three digits long.
  727. This affects the C function edit_double in \(fp)c/print.d\(fr).
  728.  
  729. \(fg)
  730. 10.3. The C Stack
  731. \(fr)
  732.      Usually, the C stack grows from the high core to the low core.
  733. But in some machines such as ECLIPSE/MV, it grows from the low to the high.
  734. The code to check whether the C stack has overflowed
  735. (or is about to overflow) depends on
  736. the direction that the C stack grows.
  737.  
  738.      In \(fp)c/main.c\(fr),
  739. the C global variable \(fp)cs_limit\(fr) is initialized;
  740. the initial value depends on the direction that the C stack grows.
  741. In the C function \(fp)eval\(fr) in \(fp)c/eval.c\(fr),
  742. \(fp)cs_limit\(fr) is compared with the address of the argument
  743. to check the C stack overflow.  This also depends on the direction.
  744.  
  745. \(fg)
  746. 10.4. Order of Arguments
  747. \(fr)
  748.      The C functions
  749. \(fp)parse_key\(fr) (in \(fp)c/bind.c\(fr)),
  750. \(fp)list\(fr) (in \(fp)c/list.d\(fr)),
  751. and \(fp)listA\(fr) (in \(fp)c/list.d\(fr))
  752. accept an arbitrary number of arguments.
  753. Usually, the first argument is placed in the lower address than other
  754. arguments, the second argument in the lower address than the rest, and so on.
  755. But in some machines such as ECLIPSE/MV, the order is reversed.
  756.  
  757. \(fg)
  758. 11. Operating-System-Dependent Parts
  759.  
  760. 11.1. Assembler File
  761. \(fr)
  762.      The assembler file \(fp)c/char_table.s\(fr) (or \(fp)c/sun_chtab.s\(fr))
  763. should be rewritten as explained in Section 5.
  764.  
  765. \(fg)
  766. 11.2. Memory Management
  767. \(fr)
  768.      The UNIX BSD versions of KCL use the \(fp)sbrk\(fr) system call
  769. to extend the process space.  Heap manipulating functions provided as
  770. the standard library of C, such as \(fp)malloc\(fr) and \(fp)calloc\(fr),
  771. are not used.  In fact, when calling \(fp)sbrk\(fr),
  772. KCL always checks whether the process' highest address has been changed
  773. after the last call of \(fp)sbrk\(fr).
  774. If the highest address has been changed,
  775. i.e., if some heap manipulating function has allocated memory,
  776. KCL reports a fatal error and exits immediately;
  777. KCL always wants to control the whole memory by itself.
  778.  
  779.      In the UNIX versions of KCL (except KCL/DGX), the following
  780. five library functions are redifined in \(fp)c/alloc.c\(fr); \(fp)malloc\(fr),
  781. \(fp)free\(fr), \(fp)realloc\(fr), \(fp)calloc\(fr) and \(fp)cfree\(fr).  You
  782. should check whether the redefinition is compatible with other library
  783. functions.
  784.  
  785. \(fg)
  786. 11.3. I/O
  787. \(fr)
  788.      For I/O, KCL only uses the standard I/O library of C;
  789. it does not use any low-level system calls.  You should only care about
  790. the deviation of the library of your machine
  791. from the standard I/O library of C.
  792. For example, the library of AOS/VS uses the name \(fp)_start\(fr)
  793. for the buffer address in the I/O buffer structure;
  794. in contrast, the library of UNIX uses the name \(fp)_base\(fr).
  795.  
  796.      Usually, the standard I/O library of C
  797. allocates the I/O buffer by calling \(fp)malloc\(fr).  In KCL,
  798. \(fp)setbuf\(fr) is used to set the buffer
  799. to prevent the I/O library from calling \(fp)malloc\(fr).  But
  800. in some cases, it is impossible to call \(fp)setbuf\(fr); for example,
  801. \(fp)getwd\(fr), which gets the current working directory,
  802. uses the standard I/O library to read directory files.
  803. To cope with those cases, the UNIX versions of KCL (except KCL/DGX)
  804. redefine \(fp)malloc\(fr) and the related functions (see Section 11.2);
  805. the redefined \(fp)malloc\(fr) allocates the I/O buffer
  806. in the standard heap of KCL.
  807.  
  808. \(fg)
  809. 11.4. The Loader
  810. \(fr)
  811.      Since the KCL compiler translates a Lisp program into a C program,
  812. KCL should have the facility
  813. to load the object file produced by the C compiler into the memory of the
  814. interpreter.  The UNIX BSD versions of KCL invoke the standard linkage editor
  815. \(fp)ld\(fr) with the \(fp)-A\(fr) option (incremental loading)
  816. to relocate the object file.
  817. The interpreter then loads the output of \(fp)ld\(fr) into the memory.
  818.  
  819.      If \(fp)ld\(fr) in your machine does not have the facility of
  820. incremental loading, you should write the relocation routine by yourself.
  821. The code that calls \(fp)ld\(fr) and reads the output
  822. of \(fp)ld\(fr) is in \(fp)c/unixfasl.c\(fr).
  823.  
  824. \(fg)
  825. 11.5. Memory Dump
  826. \(fr)
  827.      The KCL function \(fp)save\(fr) saves the whole memory into an
  828. executable file.  It is defined in \(fp)c/unixsave.c\(fr).
  829. It assumes the format of \(fp)a.out\(fr).
  830.  
  831. \(fg)
  832. 11.6. The Compiler
  833. \(fr)
  834.      \(fp)cmpnew/cmpmain.lsp\(fr) should be rewritten,
  835. if the code for the UNIX versions does not work.
  836.  
  837. \(fg)
  838. 11.7. Miscellaneous
  839. \(fr)
  840.      Programs in the following C files are OS-dependent:
  841.  
  842.     \(fp)unixfsys.c    \(fr)file system interface
  843.     \(fp)unixint.c    \(fr)interrupt handling
  844.     \(fp)unixsys.c    \(fr)KCL function \(fp)system\(fr)
  845.     \(fp)unixtime.c    \(fr)time functions
  846.  
  847. These files need not be changed when KCL is ported
  848. to machines running under UNIX BSD.
  849. But when porting KCL to machines running under UNIX System V,
  850. they will require several minor changes, depending on "the" System V.
  851.  
  852. \(fg)
  853. 12. Site-Dependent Parts
  854. \(fr)
  855.      \(fp)lsp/autoload.lsp\(fr) should be changed to setup
  856. site-dependent Lisp functions and variables.
  857. \(fp)
  858.     lisp-implementation-type
  859.     machine-type
  860.     machine-version
  861.     machine-instance
  862.     software-type
  863.     software-version
  864.     short-site-name
  865.     long-site-name
  866.  
  867.     *features*
  868.  
  869.     system:*default-time-zone*
  870.  
  871.     ed
  872.  
  873.       ...
  874. \(fr)
  875. You can also define other functions in \(fp)autoload.lsp\(fr),
  876. or set up storage parameters
  877. (by \(fp)allocate\(fr), \(fp)allocate-contiguous-pages\(fr),
  878. or \(fp)allocate-relocatable-pages\(fr)).
  879.      
  880.  
  881.  
  882.  
  883.